%STEREORECTIFY  Computes rectification transforms for each head of a calibrated stereo camera
%
%     S = cv.stereoRectify(cameraMatrix1, distCoeffs1, cameraMatrix2, distCoeffs2, imageSize, R, T)
%     [...] = cv.stereoRectify(..., 'OptionName', optionValue, ...)
%
% ## Input
% * __cameraMatrix1__ First camera matrix 3x3.
% * __distCoeffs1__ First camera distortion parameters of 4, 5, 8, 12 or 14
%   elements.
% * __cameraMatrix2__ Second camera matrix 3x3.
% * __distCoeffs2__ Second camera distortion parameters of 4, 5, 8, 12 or 14
%   elements.
% * __imageSize__ Size of the image used for stereo calibration `[w,h]`.
% * __R__ Rotation matrix between the coordinate systems of the first and the
%   second cameras, 3x3/3x1 (see cv.Rodrigues)
% * __T__ Translation vector between coordinate systems of the cameras, 3x1.
%
% ## Output
% * __S__ scalar struct having the following fields:
%   * __R1__ 3x3 rectification transform (rotation matrix) for the first
%     camera.
%   * __R2__ 3x3 rectification transform (rotation matrix) for the second
%     camera.
%   * __P1__ 3x4 projection matrix in the new (rectified) coordinate systems
%     for the first camera.
%   * __P2__ 3x4 projection matrix in the new (rectified) coordinate systems
%     for the second camera.
%   * __Q__ 4x4 disparity-to-depth mapping matrix (see cv.reprojectImageTo3D).
%   * __roi1__, __roi2__ rectangles inside the rectified images where all the
%     pixels are valid `[x,y,w,h]`. If `Alpha=0`, the ROIs cover the whole
%     images. Otherwise, they are likely to be smaller.
%
% ## Options
% * __ZeroDisparity__ If the flag is set, the function makes the principal
%   points of each camera have the same pixel coordinates in the rectified
%   views. And if the flag is not set, the function may still shift the images
%   in the horizontal or vertical direction (depending on the orientation of
%   epipolar lines) to maximize the useful image area. default true.
% * __Alpha__ Free scaling parameter. If it is -1 or absent, the function
%   performs the default scaling. Otherwise, the parameter should be between 0
%   and 1. `Alpha=0` means that the rectified images are zoomed and shifted so
%   that only valid pixels are visible (no black areas after rectification).
%   `Alpha=1` means that the rectified image is decimated and shifted so that
%   all the pixels from the original images from the cameras are retained in
%   the rectified images (no source image pixels are lost). Obviously, any
%   intermediate value yields an intermediate result between those two extreme
%   cases. default -1
% * __NewImageSize__ New image resolution after rectification. The same size
%   should be passed to cv.initUndistortRectifyMap. When [0,0] is passed
%   (default), it is set to the original `imageSize`. Setting it to larger
%   value can help you preserve details in the original image, especially when
%   there is a big radial distortion.
%
% The function computes the rotation matrices for each camera that (virtually)
% make both camera image planes the same plane. Consequently, this makes all
% the epipolar lines parallel and thus simplifies the dense stereo
% correspondence problem. The function takes the matrices computed by
% cv.stereoCalibrate as input. As output, it provides two rotation matrices
% and also two projection matrices in the new coordinates. The function
% distinguishes the following two cases:
%
% 1. **Horizontal stereo**: the first and the second camera views are shifted
%    relative to each other mainly along the x axis (with possible small
%    vertical shift). In the rectified images, the corresponding epipolar
%    lines in the left and right cameras are horizontal and have the same
%    y-coordinate. `P1` and `P2` look like:
%
%        P1 = [f 0 cx1 0;
%              0 f cy  0;
%              0 0 1   0]
%
%        P2 = [f 0 cx2 Tx*f;
%              0 f cy     0;
%              0 0 1      0]
%
%    where `Tx` is a horizontal shift between the cameras and `cx1=cx2` if
%    `ZeroDisparity` is set.
%
% 2. **Vertical stereo**: the first and the second camera views are shifted
%    relative to each other mainly in vertical direction (and probably a bit
%    in the horizontal direction too). The epipolar lines in the rectified
%    images are vertical and have the same x-coordinate. `P1` and `P2` look
%    like:
%
%        P1 = [f 0 cx  0;
%              0 f cy1 0;
%              0 0 1   0]
%
%        P2 = [f 0 cx     0;
%              0 f cy2 Ty*f;
%              0 0 1      0]
%
%    where `Ty` is a vertical shift between the cameras and `cy1=cy2` if
%    `ZeroDisparity` is set.
%
% As you can see, the first three columns of `P1` and `P2` will effectively be
% the new "rectified" camera matrices. The matrices, together with `R1` and
% `R2`, can then be passed to cv.initUndistortRectifyMap to initialize the
% rectification map for each camera.
%
% See the output of the `stereo_calibration_demo.m` sample. Some red
% horizontal lines pass through the corresponding image regions. This means
% that the images are well rectified, which is what most stereo correspondence
% algorithms rely on. The green rectangles are `roi1` and `roi2`. You see that
% their interiors are all valid pixels.
%
% See also: cv.stereoCalibrate, cv.stereoRectifyUncalibrated,
%  rectifyStereoImages
%
